home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 23.zip / BS1 part 23 / 3D construction kit.adf / Utils / fsprint.doc < prev    next >
Text File  |  1991-04-10  |  10KB  |  317 lines
  1.  
  2.  
  3.  
  4.     FSPRINT
  5.  
  6.     Freescape data file printer
  7.  
  8.  
  9.     Incentive Software Ltd
  10.  
  11.     11 February 1991
  12.  
  13.  
  14.  
  15. 1. OVERVIEW
  16. -----------
  17.  
  18. FSPRINT is designed to allow you to print out your data files
  19. saved from the 3D Construction kit.
  20.  
  21. It allows you to print out selected ranges of areas and objects,
  22. along with various other useful information, from several files
  23. at once if necessary.
  24.  
  25.  
  26. 2. NOTES FOR NON-PC MACHINES
  27. ----------------------------
  28.  
  29. All the examples in this file are for the IBM PC, which uses the
  30. MS-DOS operating system. The command line interpreter prints a
  31.  
  32. C>
  33.  
  34. prompt whilst expecting input from you, the user. Do not type
  35. this in! Other command line interpreters (CLIs) may give a
  36. different prompt.
  37.  
  38. The Amiga has a CLI built in, so the usage is exactly the same.
  39.  
  40. The Atari ST has various public domain CLIs available, or you
  41. can run FSPRINT from the desktop as follows: Double-click on
  42. FSPRINT.TTP. You will see a dialogue box appear. Type in the
  43. command line without the initial FSPRINT. So, for an example
  44. reading:
  45.  
  46. C> FSPRINT -pz -h- test.all
  47.  
  48. you would start FSPRINT by double-clicking and then type
  49.  
  50. -pz -h- test.all
  51.  
  52. into the dialogue box. After all input, don't forget to press the
  53. ENTER or RETURN key !
  54.  
  55.  
  56. 3. USAGE
  57. --------
  58.  
  59. To use FSPRINT you will need a printer. Any printer which can
  60. be connected to your computer will work, although the small print
  61. and bold modes will only work with EPSON compatible printers.
  62. Since most printers are indeed EPSON compatible, this should not
  63. pose too much of a problem.
  64.  
  65. In its simplest form, you can print out a data file by starting
  66. the program from the command line, with just the name of the file
  67. you wish to print:
  68.  
  69. C> FSPRINT TEST.ALL
  70.  
  71. This will print the file TEST.ALL to the printer. Make sure the
  72. printer is on line otherwise you will get an error message (see
  73. below).
  74.  
  75. You can print out several files at the same time by specifying
  76. each of their names in turn:
  77.  
  78. C> FSPRINT FIRST.ALL SECOND.ALL THIRD.ALL
  79.  
  80. If you find that the printer output comes out double spaced, the
  81. `r' option will fix that for you. To introduce an option, start
  82. it with either `-' or `/', so that it can be distinguished from a
  83. filename. Upper and lower case letters are taken to be the same:
  84.  
  85. C> FSPRINT -r TEST.ALL
  86.  
  87. or
  88.  
  89. C> FSPRINT /R TEST.ALL
  90.  
  91. The `r' option stops extra line feed characters being sent to the
  92. printer. The `r' option may be followed by either `0', `1' or
  93. `2'. The option `r0' sends both a carriage return and a line feed
  94. to the printer when a new line is needed. This is the default at
  95. the start. Option `r1' ( same as `r' on its own ) sends only a
  96. carriage return. `r2' sends only a linefeed. One of these will
  97. certainly work with your printer:
  98.  
  99. C> FSPRINT -r0 TEST.ALL         ( same as no `r' option at all )
  100. C> FSPRINT -r1 TEST.ALL         ( same as `r' on its own )
  101. C> FSPRINT -r2 TEST.ALL
  102.  
  103. For most purposes, these will be enough. For the adventurous -
  104. read on !
  105.  
  106. In a large file, you may wish only to print out a specified range
  107. of areas. The `a' option accomplishes this:
  108.  
  109. C> FSPRINT -a1 TEST.ALL         Print area 1 from TEST.ALL
  110.  
  111. You can specify entire ranges of areas:
  112.  
  113. C> FSPRINT /A1-5 TEST.ALL        Print areas 1 to 5 from TEST.ALL
  114.  
  115. C> FSPRINT -a-5 TEST.ALL     Print all areas up to area 5
  116.  
  117. C> FSPRINT -a5- TEST.ALL     Print all areas from area 5 on
  118.  
  119. As you can see, a range consists of either a single number, or of
  120. a start and an end number separated by a dash. If you omit the
  121. start, the first item is assumed, and if you omit the end, the
  122. last item is assumed. If you specify no range, no areas are
  123. specified: an `a' on its own means "print none of the areas". If
  124. you don't even include the option itself, everything will be
  125. printed.
  126.  
  127. You can specify different ranges for different files on the same
  128. command line by preceding each file by the range you require:
  129.  
  130. C> FSPRINT -a1 FIRST.ALL -a3-7 SECOND.ALL
  131.  
  132. would print area 1 from FIRST.ALL and areas 3 to 7 from
  133. SECOND.ALL.
  134.  
  135. You can print only specified objects, too, with the -o option:
  136.  
  137. C> FSPRINT -a1 -o10-50 TEST.ALL
  138.  
  139. This would print only object numbers 10 to 50 from area 1 of
  140. TEST.ALL. You can join options together, so that the previous
  141. example could also be written as:
  142.  
  143. C> FSPRINT -a1o10-50 TEST.ALL
  144.  
  145. Entrances and animators can be specified by the `e' and `m'
  146. options:
  147.  
  148. C> FSPRINT -a1e1-9o10-50m5-7 TEST.ALL
  149.  
  150. Going through this one thing at a time, we have area 1 only,
  151. entrances 1 to 9, objects 10-50 and animators 5 to 7, all from
  152. the file TEST.ALL.  You can similarly limit the local conditions
  153. that are printed using the `l' option.
  154.  
  155. On each printout, the data file header is printed with
  156. information about the world as a whole, the key and icon
  157. information, the instruments, the colours and the global
  158. conditions. The header, key, instrument and colour information
  159. can be turned on or off using the `h', `k', `i' and `c' options.
  160. On their own, or followed by a `+' sign, they turn each part of
  161. the printing on, and if followed by a `-', they turn it off. The
  162. global conditions are specified as a range following the `g'
  163. option.
  164.  
  165. C> FSPRINT -h-i-k-c-g4-6a1-9 TEST.ALL
  166.  
  167. This prints no header, no istruments, no keys and no colours, but
  168. does print global conditions 4 to 6 and areas 1 to 9 from file
  169. TEST.ALL.
  170.  
  171. Don't worry if you can't remeber all this. Just typing
  172.  
  173. C> FSPRINT
  174.  
  175. will give a quick reminder of all the options.
  176.  
  177. It is quite useful to be able to print out several ranges of
  178. things, from the same data file. Obviously, you will not want the
  179. header, etc, on subsequent ranges, so you could do it like this:
  180.  
  181. C> FSPRINT -a1-5 TEST.ALL -h-k-i-c-a10-15 TEST.ALL
  182.  
  183. Which would print the header , etc, plus areas 1 to 5, then areas
  184. 1 to 10. There is a much easier way of doing this. Just separate
  185. the options with a semicolon:
  186.  
  187. C> FSPRINT -a1-5;a10-15 TEST.ALL
  188.  
  189. This has exactly the same effect. The first range is printed
  190. using the options you have given plus the default header, etc.
  191. The second range is printed using only those options you supply.
  192. Nothing defaults. If you explicitly want the header, you can turn
  193. it on using `h+':
  194.  
  195. C> FSPRINT -a1-5;h+a10-15 TEST.ALL
  196.  
  197. The headers, keys, instruments and colours default on at the
  198. start of each file:
  199.  
  200. C> FSPRINT -a1-5;a10-15 FIRST.ALL SECOND.ALL
  201.  
  202. Would print the header, etc, and areas 1 to 5 and 10 to 15 of
  203. file FIRST.ALL and all of file SECOND.ALL. The options revert to
  204. normal when a new file is printed. If you wanted to print only
  205. areas 1 to 9 of SECOND.ALL, you would use:
  206.  
  207. C> FSPRINT -a1-5;a10-15 FIRST.ALL -a1-9 SECOND.ALL
  208.  
  209. If you have an EPSON compatible printer, you can print all the
  210. titles, object names, etc, in bold type. This will make them
  211. easier to pick out from the listing. To do this, use the `b'
  212. option:
  213.  
  214. C> FSPRINT -b TEST.ALL
  215.  
  216. Right, now for the clever bits. You can use each of the following
  217. options only once - they do not switch off and they cannot be
  218. cancelled. Firstly, the `s' option. For EPSON compatible
  219. printers, you can print in very small type, which squeezes almost
  220. twice as much listing on a page of paper. To do this, specify the
  221. -s option before the first filename:
  222.  
  223. C> FSPRINT -s TEST.ALL
  224.  
  225. Also, you can redirect the printer output to a file, or the
  226. console (screen) using the `p' option. This is followed
  227. immediately (no spaces) by the name of the file that will act as
  228. your printer:
  229.  
  230. C> FSPRINT -pPRINT.OUT TEST.ALL
  231.  
  232. This will create a file called PRINT.OUT which will contain
  233. exactly what would have been sent to the printer.
  234.  
  235. You cannot specify multiple print files, and the -p option must
  236. be on its own and the first option on the command line. The
  237. following examples are wrong:                    Why?
  238.  
  239. C> FSPRINT -s -pPRINT.OUT TEST.ALL         `s' before `p'
  240.  
  241. C> FSPRINT -spPRINT.OUT TEST.ALL         `p' not alone
  242.  
  243. C> FSPRINT -pL.1ST FIRST.ALL -pL.2ND SECOND.ALL  Two `p's
  244.  
  245. C> FSPRINT -pPRINT.OUTs TEST.ALL         `s' part of name
  246.  
  247. In the last case, the computer will try to create a file called
  248. `PRINT.OUTS', and will probably fail. This example is OK:
  249.  
  250. C> FSPRINT -pPRINT.OUT -s TEST.ALL
  251.  
  252. To direct the output to the screen, specify `CON:' as the
  253. filename:
  254.  
  255. C> FSPRINT -pCON: TEST.ALL
  256.  
  257.  
  258. 4. ERRORS
  259. ---------
  260.  
  261. In addition to the usual operating system errors, such as
  262. write protected disks, there are several situations that FSPRINT
  263. will recognise as errors. You will then get one of the following
  264. messages:
  265.  
  266. ERROR: Cannot open file <filename>
  267.     The file <filename>, which is to be printed out, cannot
  268.     be opened. Check that it exists.
  269.  
  270. ERROR: `<letter>' is an invalid option
  271.     The letter displayed is not one of the allowed option
  272.     letters (abceghiklmopr or ;).
  273.  
  274. ERROR: Invalid range
  275.     The range following the option letter shown is wrong -
  276.     the start is larger than the end.
  277.  
  278. ERROR: Cannot open <filename> for output
  279.     The alternative printer output cannot be opened for some
  280.     reason. Check that it is a valid filename.
  281.  
  282. ERROR: Only one alternative printer output allowed
  283.     The printer output has already been redirected to an
  284.     alternative file. It cannot be redirected again.
  285.  
  286. ERROR: Cannot allocate enough workspace
  287.     There is not enough memory for FSPRINT to use as
  288.     workspace.
  289.  
  290.  
  291. 5. CREDITS
  292. ----------
  293.  
  294. FSPRINT was originally written using Turbo C on the IBM PC by
  295. Sean Ellis, then ported to Lattice C for the Amiga and Atari ST
  296. by Paul Gregory.
  297.  
  298. FSPRINT is Copyright Incentive Software Ltd 1991.
  299.  
  300. Incentive Software Ltd ("The Company") hereby disclaims all
  301. warranties relating to this software, whether express or implied,
  302. including without limitation any implied warranties of
  303. merchantability or fitness for a particular purpose. The Company
  304. will not be liable for any special, incidental, consequential,
  305. indirect or similar damages due to loss of data or any other
  306. reason, even if The Company or an agent of The Company has been
  307. advised of the possibility of such damages.  In no event shall
  308. The Company's liability for any damages ever exceed the price paid
  309. for the license to use software, regardless of the form of the
  310. claim.  The person using the software bears all risk as to the
  311. quality and performance of the software.
  312.  
  313.  
  314. 6. CONTACT ADDRESS
  315. ------------------
  316.  
  317. <<<< INSERT DOMARK ADDRESS HERE >>>>